home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 101-125 / scopedisk102 / kdlib / fr_user.doc < prev    next >
Text File  |  1995-03-19  |  13KB  |  292 lines
  1.                           kd_freq.library  1.00
  2.  
  3.                      File Requester User Documentation
  4.                      ---------------------------------
  5.  
  6.                            By:  Khalid Aldoseri 
  7.                            --------------------
  8.  
  9. A File Requester is used to select a file name from the existing files on a
  10. system, or to enter a new file name.  This file requester (FR) supports all
  11. normal features in a FR plus a lot of special features as desribed below.
  12.  
  13.  
  14. File Requester Features:
  15.  
  16.  1. Path Gadget: (string gadget at top of window)
  17.     This contains the path to the currently displayed directory.  You can
  18.     enter any directory name directly into it if you like by clicking in
  19.     it and editing the text there.
  20.  
  21.     Notes:
  22.  
  23.     If you insert a disk into a drive that has been selected in the Path
  24.     gadget the disk's directory will automatically be read and displayed.
  25.  
  26.     If the current disk is removed from the drive, the FR will clear the file
  27.     list and bring up the device name (not the old disk name) in the Path
  28.     gadget.  This means that you can take a disk out of the drive and insert
  29.     a new one and the FR will keep up with you if the current device is the
  30.     one that you are using.  This only works for devices DF0: to DF3:.
  31.  
  32.     If the user enters the name of an actual file into the Path gadget, then
  33.     the name will be split into its path and filename components and handled
  34.     accordingly.
  35.  
  36.  2. File Gadget: (string gadget below Path gadget)
  37.     This contains the currently selected file.  You can manually edit the
  38.     filename by clicking in it and editing the text.  It also supports the
  39.     following features:
  40.  
  41.     - Auto-Find:
  42.       If you type any filename in the File gadget and hit return, the
  43.       filename closest to the one you typed in will be shown at the top
  44.       of the file list.
  45.  
  46.     - Auto-Complete:
  47.       If you type the first few characters of a file name and end the name
  48.       with either a '?' or a '/' and hit return, the first matching filename
  49.       from the file list will be used to complete the filename in the File
  50.       gadget.
  51.  
  52.     - Auto-Activate:
  53.       You can immediately type in a filename if no string gadget is active.
  54.       This will automatically activate the File gadget.
  55.  
  56.  3. File List:  (set of gadgets that display the file list)
  57.     To select any file just click on it once and it will show up in the File
  58.     gadget, unless the entry you clicked on was a directory, in which case
  59.     the FR will automatically display the directory selected.  The display
  60.     format is:
  61.  
  62.     test.file  *         11381  09-Dec-89  11:50    ----rwed
  63.        |       |           |        |        |         |
  64.     filename   |          size     date     time   protection
  65.               filenote                                bits
  66.               marker
  67.  
  68.     If the file entry is a directory, it will be displayed in a different
  69.     color and it will display '-dir-' instead of the file size.  The actual
  70.     data displayed depends on the size of the window, refer to the section
  71.     on 'Resize Gadget' for details.
  72.  
  73.     Double-clicking on a file name will simulate the OK gadget.
  74.  
  75.     If the entry has a filenote marker, then that file has a comment (or
  76.     file note). To see this comment, click on that entry and the comment
  77.     will be displayed in its place in the file list.  To remove the note
  78.     from the display just click on the prop gadget.
  79.  
  80.     Clicking the right mouse button while the pointer is on the file list
  81.     area will cycle through one of three modes:
  82.  
  83.        a.  Normal mode:  File list shows the selected directory.
  84.        b.  Device list:  File list shows the currently mounted devices
  85.                          by volume name.
  86.        c.  Assign list:  File list shows all assigns.
  87.  
  88.  4. OK Gadget: (bottom left of window)
  89.     Click on this gadget when you're happy with the directory/filename you
  90.     have selected.  This tells the calling program that you accept these
  91.     selections.  Hitting the TAB key also has the same effect.
  92.  
  93.  5. Cancel Gadget: (bottom right of window)
  94.     This cancels the file requester and aborts the filename selection.
  95.     Hitting the 'Esc' key also has the same effect.
  96.  
  97.  6. Close Window Gadget:  (standard close window gadget)
  98.     Does the same as 'Cancel Gadget'.
  99.  
  100.  7. Wild Gadget: (string gadget below File List)
  101.     The pattern entered in this gadget controls what files are displayed
  102.     in the File List.  This take a standard AmigaDOS wildcard pattern and
  103.     applies it to the file list as files are being read from the device.
  104.     This defaults to '#?'.
  105.  
  106.     Supported wildcards in pattern:
  107.  
  108.           1.  Standard AmigaDOS Wildcards:
  109.           --------------------------------
  110.  
  111.           ?   Matches any single character
  112.           #p  Match any number of occurences of the pattern p
  113.           %   Matches the null string
  114.           ()  Make a group of characters into a single pattern
  115.           |   The OR operator
  116.           '   Disable wildcard interpretation of next character
  117.               (unless it is an extended wildcard as shown below.)
  118.  
  119.           2.  Extended Wildcards:
  120.           -----------------------
  121.  
  122.           These are wildcards not supported by the standard AmigaDOS
  123.           convention, but expand it to make it more versatile.
  124.  
  125.           'd  Matches any single digit.  (0 to 9)
  126.           'a  Matches any single alpha character. (a to z)
  127.           'n  Matches any single alphanumeric character.
  128.  
  129.        For examples of standard wildcard usage, look up any AmigaDOS
  130.        tutorial book.
  131.  
  132.        Examples of extended wildcards:
  133.  
  134.        Pattern     Matching possibilities
  135.        -------     ----------------------
  136.        test'n      test0, test1, test9, testa, testA, testz, testZ
  137.        test'd      test0, test1, test9
  138.        test'a      testa, testA, testz, testZ
  139.        test 'd     test 1, test 2, test 9
  140.        test#'d     test1, test100, test10234
  141.        #'a#'d      a1, ab12, abc1, abc123, adks34234
  142.                    (matches any string with some or no alpha characters,
  143.                    then some or no digits.)
  144.        #'a'd#'d.c  a1.c, a203.c, 100.c, 1.c, adsdfs931234.c
  145.                    (matches any string that starts with some of no alpha
  146.                    characters, then at least 1 or more digits, and ends
  147.                    with .c)
  148.  
  149.  8. Scroll Up:  (up-arrow above the proportional gadget)
  150.     This scrolls the file list up at a slow speed if you click it
  151.     with the left mouse button, or it will scroll the file list down
  152.     if you click it with the right mouse button.  If you hold down both
  153.     buttons at the same time, the right button will take priority.
  154.  
  155.  9. Scroll Down:  (down-arrow below the proportional gadget)
  156.     Same as above expect that it moves the list a lot faster and the mouse
  157.     button directions are reversed.
  158.  
  159. 10. Prop Gadget:  (proportional gadget across the center of the window)
  160.     This gadget represents the position of the currently displayed files
  161.     in the File List in relation to the total files in the selected
  162.     directory.  You can move around the list by holding down the Prop
  163.     Gadget with the left mouse button and moving the gadget up and down.
  164.  
  165.     If you click the right mouse button over the Prop gadget it will move
  166.     to the top of the file list, unless it is already at the top in which
  167.     case it will move to the bottom of the list.
  168.  
  169. 11. Parent:  (up-arrow to the left of the Path string gadget)
  170.     If you click on this gadget with the left mouse button, the FR will
  171.     display the parent of the current directory, if there is one.
  172.     If you click on it with the right button, it will display the root
  173.     directory of the currently selected device.
  174.  
  175. 12. Disk Gadgets:  (set of disk icons across the left of the window)
  176.     These are disk icons that represent the currently mounted storage
  177.     devices in the system.  If you click on any disk icon with the left
  178.     mouse button the root directory of the selected device will be
  179.     displayed.  You can scroll through the mounted disk list via the
  180.     'Disk Scroll Up' and 'Disk Scroll Down' arrow gadgets.
  181.  
  182.     If you click on the right mouse button over any disk icon, you will get
  183.     info about the device displayed in the file list area.  The file list is
  184.     not erased from memory, you just have to click on the prop gadget or the
  185.     up or down scroll gadgets and the file list will reappear.
  186.     Note:  If there isn't enough space to display 4 lines in the file list
  187.     area, this function will not work.
  188.  
  189. 13. Disk Scroll Up:  (up-arrow in the top left-hand corner)
  190.     This scrolls the list of 'mounted disks' up.  It only works if the
  191.     number of available devices is too big to fit in the current window.
  192.  
  193. 14. Disk Scroll Down:  (down-arrow in the top left-hand corner)
  194.     Same as above, but scrolls the list down.
  195.  
  196. 15. Resize Gadget: (bottom 5 lines across window)
  197.     The FR is resizable by the user.  The resize gadget is marked by a 
  198.     tiny arrow in the bottom-right corner, but it actually occupies the
  199.     bottom 5 lines across the window.  Just click there and resize
  200.     the window.  The whole requester will resize accordingly.
  201.  
  202.     Resizing the window horizontally will make space for more info about
  203.     the file to be display.  This is based on the following method:
  204.     The FR checks to see the longest file name in the list and it
  205.     fits in whatever extra data it can starting from the file date, file
  206.     time and finally protection bits.
  207.  
  208. 16. Next Directory:  (gadget with 'Next' in it, left top corner)
  209.     The Next Directory gadget stores the current directory and all its
  210.     files into a temporary buffer and will then provide you with a new work
  211.     buffer to use.  You can then go back to that old directory immediately by
  212.     clicking on the Next gadget until you get back to it.  The directory is
  213.     displayed immediately and does not have to be read back again from the
  214.     drive.  This can be repeated for upto 5 diretories stored at the same
  215.     time.  When you use the 'Next' gadget, the current buffer # is displayed
  216.     at the bottom of the FR.  If the buffer is a new one, it will display
  217.     "Buffer # x  (empty)".
  218.  
  219.     The following data is stored in each buffer:
  220.        - The full path name of the directory.
  221.        - All the files in the directory along with their sizes, date,
  222.          time and protection settings.
  223.        - The number of files and directories in the directory.
  224.        - The position where the scroll bar was in.  (This means that
  225.          when you return to a directory, the file list will be exactly
  226.          where you left it.)
  227.        - The current filename in the File gadget.
  228.  
  229. 17. Preset Resize Gadgets:  (3 small box gadgets left of 'Scroll Down Gadget')
  230.     These gadgets immediately resize the FR to small, normal, and full screen
  231.     respectively from left to right.  This action will also automatically
  232.     center the FR in the screen.  If the FR is already at the requested size,
  233.     then this request will be ignored.
  234.  
  235. 18. No .info Gadget:  (small box with 'I' in it, above 'Cancel' gadget)
  236.     If the No .info Gadget is active, it will have two lines drawn diagonally
  237.     across it.  This tells the FR not to display files ending with '.info' in
  238.     the file list.  This gadget is actually a toggle switch.
  239.  
  240.  
  241. Notes:
  242.  
  243. -   The FR stays 'live' while reading the directory, i.e. you can abort the
  244.     directory read at any time by selecting a new directory.  You can also
  245.     scroll through the file list or resize the window and the FR will keep
  246.     on reading the directory.
  247.  
  248. -   Each buffer used allocates memory in 2k chunks as it needs them.
  249.     Average memory usage is 70 files for a 2k buffer.  The only limit
  250.     to number of files per directory is available memory.  If the FR
  251.     runs out of memory, it will inform the user that the directory
  252.     was truncated.
  253.  
  254. -   The FR will always try to come back up where it was previously, and in
  255.     the same size.  If it can't do that, it will move/resize to attempt to
  256.     be as close as possible to what it was.
  257.  
  258. -   Keyboard commands:   (These only work if no string gadget is active)
  259.  
  260.         Enter or CR     Activate Path gadget.
  261.         Space Bar       Active Wildcard gadget.
  262.         Escape key      Cancel requester.
  263.         Tab key         OK requester.
  264.  
  265. -   Error Messages:
  266.  
  267.     If the FR cannot access a device, it will report one of the following
  268.     errors:
  269.  
  270.         - No disk in drive.     (drive empty)
  271.         - Not a DOS Disk.       (bad or kickstart disk)
  272.         - Can't find Path.      (bad device or directory name)
  273.         - DOS Error: xxx.       (where xxx is the DOS error number.)
  274.  
  275.  
  276. -   Please send any comments, suggestions, bug reports, etc. to me either on
  277.     Compuserve (75166,2531) or to:
  278.  
  279.                       /-------------------\
  280.                       | Khalid Aldoseri   |
  281.                       | P.O. Box 3300     |
  282.                       | Manama, Bahrain.  |
  283.                       | Tel: (973) 690066 |
  284.                       | Fax: (973) 694777 |
  285.                       \-------------------/
  286.  
  287.                       Compuserve 75166,2531
  288.  
  289.  
  290.                   Copyright 1990  Khalid Aldoseri.
  291.                          16 January 1990.
  292.